home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / account.h next >
C/C++ Source or Header  |  2005-10-18  |  18KB  |  687 lines
  1. /**
  2.  * @file account.h Account API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  *
  25.  * @see @ref account-signals
  26.  */
  27. #ifndef _GAIM_ACCOUNT_H_
  28. #define _GAIM_ACCOUNT_H_
  29.  
  30. #include <glib.h>
  31.  
  32. typedef struct _GaimAccountUiOps GaimAccountUiOps;
  33. typedef struct _GaimAccount      GaimAccount;
  34.  
  35. typedef gboolean (*GaimFilterAccountFunc)(GaimAccount *account);
  36.  
  37. #include "connection.h"
  38. #include "log.h"
  39. #include "proxy.h"
  40. #include "prpl.h"
  41.  
  42. struct _GaimAccountUiOps
  43. {
  44.     void (*notify_added)(GaimAccount *account, const char *remote_user,
  45.                          const char *id, const char *alias,
  46.                          const char *message);
  47. };
  48.  
  49. struct _GaimAccount
  50. {
  51.     char *username;             /**< The username.                        */
  52.     char *alias;                /**< The current alias.                   */
  53.     char *password;             /**< The account password.                */
  54.     char *user_info;            /**< User information.                    */
  55.  
  56.     char *buddy_icon;           /**< The buddy icon.                      */
  57.  
  58.     gboolean remember_pass;     /**< Remember the password.               */
  59.  
  60.     char *protocol_id;          /**< The ID of the protocol.              */
  61.  
  62.     GaimConnection *gc;         /**< The connection handle.               */
  63.  
  64.     GHashTable *settings;       /**< Protocol-specific settings.          */
  65.     GHashTable *ui_settings;    /**< UI-specific settings.                */
  66.  
  67.     GaimProxyInfo *proxy_info;  /**< Proxy information.  This will be set */
  68.                                 /*   to NULL when the account inherits    */
  69.                                 /*   proxy settings from global prefs.    */
  70.  
  71.     GSList *permit;             /**< Permit list.                         */
  72.     GSList *deny;               /**< Deny list.                           */
  73.     int perm_deny;              /**< The permit/deny setting.             */
  74.     GaimLog *system_log;        /**< The system log                       */
  75.  
  76.     void *ui_data;             /**< The UI can put data here.              */
  77. };
  78.  
  79. #ifdef __cplusplus
  80. extern "C" {
  81. #endif
  82.  
  83. /**************************************************************************/
  84. /** @name Account API                                                     */
  85. /**************************************************************************/
  86. /*@{*/
  87.  
  88. /**
  89.  * Creates a new account.
  90.  *
  91.  * @param username    The username.
  92.  * @param protocol_id The protocol ID.
  93.  */
  94. GaimAccount *gaim_account_new(const char *username, const char *protocol_id);
  95.  
  96. /**
  97.  * Destroys an account.
  98.  *
  99.  * @param account The account to destroy.
  100.  */
  101. void gaim_account_destroy(GaimAccount *account);
  102.  
  103. /**
  104.  * Connects to an account.
  105.  *
  106.  * @param account The account to connect to.
  107.  *
  108.  * @return The gaim connection.
  109.  */
  110. GaimConnection *gaim_account_connect(GaimAccount *account);
  111.  
  112. /**
  113.  * Registers an account.
  114.  *
  115.  * @param account The account to register.
  116.  *
  117.  * @return The gaim connection.
  118.  */
  119. GaimConnection *gaim_account_register(GaimAccount *account);
  120.  
  121. /**
  122.  * Disconnects from an account.
  123.  *
  124.  * @param account The account to disconnect from.
  125.  *
  126.  * @return The gaim connection.
  127.  */
  128. void gaim_account_disconnect(GaimAccount *account);
  129.  
  130. /**
  131.  * Notifies the user that the account was added to a remote user's
  132.  * buddy list.
  133.  *
  134.  * This will present a dialog so that the local user can add the buddy,
  135.  * if not already added.
  136.  *
  137.  * @param account The account that was added.
  138.  * @param remote_user The name of the user that added this account.
  139.  * @param id          The optional ID of the local account. Rarely used.
  140.  * @param alias       The optional alias of the user.
  141.  * @param message     The optional message sent from the user adding you.
  142.  */
  143. void gaim_account_notify_added(GaimAccount *account, const char *remote_user,
  144.                                const char *id, const char *alias,
  145.                                const char *message);
  146.  
  147. /**
  148.  * Notifies the user that the account was added to a remote user's
  149.  * buddy list and asks the user if they want to add the remote user to their
  150.  * buddy list.
  151.  *
  152.  * This will present a dialog informing the local user that the remote user
  153.  * added them to the remote users buddy list and will ask if they want to add
  154.  * the remote user to the local buddy list.
  155.  *
  156.  * @param account The account that was added.
  157.  * @param remote_user The name of the user that added this account.
  158.  * @param id          The optional ID of the local account. Rarely used.
  159.  * @param alias       The optional alias of the user.
  160.  * @param message     The optional message sent from the user adding you.
  161.  */
  162. void gaim_account_request_add(GaimAccount *account, const char *remote_user,
  163.                               const char *id, const char *alias,
  164.                               const char *message);
  165.  
  166. /**
  167.  * Requests information from the user to change the account's password.
  168.  *
  169.  * @param account The account to change the password on.
  170.  */
  171. void gaim_account_request_change_password(GaimAccount *account);
  172.  
  173. /**
  174.  * Requests information from the user to change the account's
  175.  * user information.
  176.  *
  177.  * @param account The account to change the user information on.
  178.  */
  179. void gaim_account_request_change_user_info(GaimAccount *account);
  180.  
  181. /**
  182.  * Sets the account's username.
  183.  *
  184.  * @param account  The account.
  185.  * @param username The username.
  186.  */
  187. void gaim_account_set_username(GaimAccount *account, const char *username);
  188.  
  189. /**
  190.  * Sets the account's password.
  191.  *
  192.  * @param account  The account.
  193.  * @param password The password.
  194.  */
  195. void gaim_account_set_password(GaimAccount *account, const char *password);
  196.  
  197. /**
  198.  * Sets the account's alias.
  199.  *
  200.  * @param account The account.
  201.  * @param alias   The alias.
  202.  */
  203. void gaim_account_set_alias(GaimAccount *account, const char *alias);
  204.  
  205. /**
  206.  * Sets the account's user information
  207.  *
  208.  * @param account   The account.
  209.  * @param user_info The user information.
  210.  */
  211. void gaim_account_set_user_info(GaimAccount *account, const char *user_info);
  212.  
  213. /**
  214.  * Sets the account's buddy icon.
  215.  *
  216.  * @param account The account.
  217.  * @param icon    The buddy icon file.
  218.  */
  219. void gaim_account_set_buddy_icon(GaimAccount *account, const char *icon);
  220.  
  221. /**
  222.  * Sets the account's protocol ID.
  223.  *
  224.  * @param account     The account.
  225.  * @param protocol_id The protocol ID.
  226.  */
  227. void gaim_account_set_protocol_id(GaimAccount *account,
  228.                                   const char *protocol_id);
  229.  
  230. /**
  231.  * Sets the account's connection.
  232.  *
  233.  * @param account The account.
  234.  * @param gc      The connection.
  235.  */
  236. void gaim_account_set_connection(GaimAccount *account, GaimConnection *gc);
  237.  
  238. /**
  239.  * Sets whether or not this account should save its password.
  240.  *
  241.  * @param account The account.
  242.  * @param value   @c TRUE if it should remember the password.
  243.  */
  244. void gaim_account_set_remember_password(GaimAccount *account, gboolean value);
  245.  
  246. /**
  247.  * Sets whether or not this account should check for mail.
  248.  *
  249.  * @param account The account.
  250.  * @param value   @c TRUE if it should check for mail.
  251.  */
  252. void gaim_account_set_check_mail(GaimAccount *account, gboolean value);
  253.  
  254. /**
  255.  * Sets whether or not this account should auto-login for the specified
  256.  * UI.
  257.  *
  258.  * @param account The account.
  259.  * @param ui      The UI.
  260.  * @param value   @c TRUE if it should check for mail.
  261.  */
  262. void gaim_account_set_auto_login(GaimAccount *account, const char *ui,
  263.                                  gboolean value);
  264.  
  265. /**
  266.  * Sets the account's proxy information.
  267.  *
  268.  * @param account The account.
  269.  * @param info    The proxy information.
  270.  */
  271. void gaim_account_set_proxy_info(GaimAccount *account, GaimProxyInfo *info);
  272.  
  273. /**
  274.  * Clears all protocol-specific settings on an account.
  275.  *
  276.  * @param account The account.
  277.  */
  278. void gaim_account_clear_settings(GaimAccount *account);
  279.  
  280. /**
  281.  * Sets a protocol-specific integer setting for an account.
  282.  *
  283.  * @param account The account.
  284.  * @param name    The name of the setting.
  285.  * @param value   The setting's value.
  286.  */
  287. void gaim_account_set_int(GaimAccount *account, const char *name, int value);
  288.  
  289. /**
  290.  * Sets a protocol-specific string setting for an account.
  291.  *
  292.  * @param account The account.
  293.  * @param name    The name of the setting.
  294.  * @param value   The setting's value.
  295.  */
  296. void gaim_account_set_string(GaimAccount *account, const char *name,
  297.                              const char *value);
  298.  
  299. /**
  300.  * Sets a protocol-specific boolean setting for an account.
  301.  *
  302.  * @param account The account.
  303.  * @param name    The name of the setting.
  304.  * @param value   The setting's value.
  305.  */
  306. void gaim_account_set_bool(GaimAccount *account, const char *name,
  307.                            gboolean value);
  308.  
  309. /**
  310.  * Sets a UI-specific integer setting for an account.
  311.  *
  312.  * @param account The account.
  313.  * @param ui      The UI name.
  314.  * @param name    The name of the setting.
  315.  * @param value   The setting's value.
  316.  */
  317. void gaim_account_set_ui_int(GaimAccount *account, const char *ui,
  318.                              const char *name, int value);
  319.  
  320. /**
  321.  * Sets a UI-specific string setting for an account.
  322.  *
  323.  * @param account The account.
  324.  * @param ui      The UI name.
  325.  * @param name    The name of the setting.
  326.  * @param value   The setting's value.
  327.  */
  328. void gaim_account_set_ui_string(GaimAccount *account, const char *ui,
  329.                                 const char *name, const char *value);
  330.  
  331. /**
  332.  * Sets a UI-specific boolean setting for an account.
  333.  *
  334.  * @param account The account.
  335.  * @param ui      The UI name.
  336.  * @param name    The name of the setting.
  337.  * @param value   The setting's value.
  338.  */
  339. void gaim_account_set_ui_bool(GaimAccount *account, const char *ui,
  340.                               const char *name, gboolean value);
  341.  
  342. /**
  343.  * Returns whether or not the account is connected.
  344.  *
  345.  * @param account The account.
  346.  *
  347.  * @return @c TRUE if connected, or @c FALSE otherwise.
  348.  */
  349. gboolean gaim_account_is_connected(const GaimAccount *account);
  350.  
  351. /**
  352.  * Returns the account's username.
  353.  *
  354.  * @param account The account.
  355.  *
  356.  * @return The username.
  357.  */
  358. const char *gaim_account_get_username(const GaimAccount *account);
  359.  
  360. /**
  361.  * Returns the account's password.
  362.  *
  363.  * @param account The account.
  364.  *
  365.  * @return The password.
  366.  */
  367. const char *gaim_account_get_password(const GaimAccount *account);
  368.  
  369. /**
  370.  * Returns the account's alias.
  371.  *
  372.  * @param account The account.
  373.  *
  374.  * @return The alias.
  375.  */
  376. const char *gaim_account_get_alias(const GaimAccount *account);
  377.  
  378. /**
  379.  * Returns the account's user information.
  380.  *
  381.  * @param account The account.
  382.  *
  383.  * @return The user information.
  384.  */
  385. const char *gaim_account_get_user_info(const GaimAccount *account);
  386.  
  387. /**
  388.  * Returns the account's buddy icon filename.
  389.  *
  390.  * @param account The account.
  391.  *
  392.  * @return The buddy icon filename.
  393.  */
  394. const char *gaim_account_get_buddy_icon(const GaimAccount *account);
  395.  
  396. /**
  397.  * Returns the account's protocol ID.
  398.  *
  399.  * @param account The account.
  400.  *
  401.  * @return The protocol ID.
  402.  */
  403. const char *gaim_account_get_protocol_id(const GaimAccount *account);
  404.  
  405. /**
  406.  * Returns the account's protocol name.
  407.  *
  408.  * @param account The account.
  409.  *
  410.  * @return The protocol name.
  411.  */
  412. const char *gaim_account_get_protocol_name(const GaimAccount *account);
  413.  
  414. /**
  415.  * Returns the account's connection.
  416.  *
  417.  * @param account The account.
  418.  *
  419.  * @return The connection.
  420.  */
  421. GaimConnection *gaim_account_get_connection(const GaimAccount *account);
  422.  
  423. /**
  424.  * Returns whether or not this account should save its password.
  425.  *
  426.  * @param account The account.
  427.  *
  428.  * @return @c TRUE if it should remember the password.
  429.  */
  430. gboolean gaim_account_get_remember_password(const GaimAccount *account);
  431.  
  432. /**
  433.  * Returns whether or not this account should check for mail.
  434.  *
  435.  * @param account The account.
  436.  *
  437.  * @return @c TRUE if it should check for mail.
  438.  */
  439. gboolean gaim_account_get_check_mail(const GaimAccount *account);
  440.  
  441. /**
  442.  * Returns whether or not this account should auto-login for the
  443.  * specified UI.
  444.  *
  445.  * @param account The account.
  446.  * @param ui      The UI.
  447.  *
  448.  * @return @c TRUE if it should auto-login on this UI.
  449.  */
  450. gboolean gaim_account_get_auto_login(const GaimAccount *account,
  451.                                      const char *ui);
  452.  
  453. /**
  454.  * Returns the account's proxy information.
  455.  *
  456.  * @param account The account.
  457.  *
  458.  * @return The proxy information.
  459.  */
  460. GaimProxyInfo *gaim_account_get_proxy_info(const GaimAccount *account);
  461.  
  462. /**
  463.  * Returns a protocol-specific integer setting for an account.
  464.  *
  465.  * @param account       The account.
  466.  * @param name          The name of the setting.
  467.  * @param default_value The default value.
  468.  *
  469.  * @return The value.
  470.  */
  471. int gaim_account_get_int(const GaimAccount *account, const char *name,
  472.                          int default_value);
  473.  
  474. /**
  475.  * Returns a protocol-specific string setting for an account.
  476.  *
  477.  * @param account       The account.
  478.  * @param name          The name of the setting.
  479.  * @param default_value The default value.
  480.  *
  481.  * @return The value.
  482.  */
  483. const char *gaim_account_get_string(const GaimAccount *account,
  484.                                     const char *name,
  485.                                     const char *default_value);
  486.  
  487. /**
  488.  * Returns a protocol-specific boolean setting for an account.
  489.  *
  490.  * @param account       The account.
  491.  * @param name          The name of the setting.
  492.  * @param default_value The default value.
  493.  *
  494.  * @return The value.
  495.  */
  496. gboolean gaim_account_get_bool(const GaimAccount *account, const char *name,
  497.                                gboolean default_value);
  498.  
  499. /**
  500.  * Returns a UI-specific integer setting for an account.
  501.  *
  502.  * @param account       The account.
  503.  * @param ui            The UI name.
  504.  * @param name          The name of the setting.
  505.  * @param default_value The default value.
  506.  *
  507.  * @return The value.
  508.  */
  509. int gaim_account_get_ui_int(const GaimAccount *account, const char *ui,
  510.                             const char *name, int default_value);
  511.  
  512. /**
  513.  * Returns a UI-specific string setting for an account.
  514.  *
  515.  * @param account       The account.
  516.  * @param ui            The UI name.
  517.  * @param name          The name of the setting.
  518.  * @param default_value The default value.
  519.  *
  520.  * @return The value.
  521.  */
  522. const char *gaim_account_get_ui_string(const GaimAccount *account,
  523.                                        const char *ui, const char *name,
  524.                                        const char *default_value);
  525.  
  526. /**
  527.  * Returns a UI-specific boolean setting for an account.
  528.  *
  529.  * @param account       The account.
  530.  * @param ui            The UI name.
  531.  * @param name          The name of the setting.
  532.  * @param default_value The default value.
  533.  *
  534.  * @return The value.
  535.  */
  536. gboolean gaim_account_get_ui_bool(const GaimAccount *account, const char *ui,
  537.                                   const char *name, gboolean default_value);
  538.  
  539.  
  540. /**
  541.  * Returns the system log for an account.
  542.  * Create it if it doesn't already exist.
  543.  *
  544.  * @param account The account.
  545.  *
  546.  * @return The log.
  547.  */
  548. GaimLog *gaim_account_get_log(GaimAccount *account);
  549.  
  550. /**
  551.  * Frees the system log of an account
  552.  *
  553.  * @param account The account.
  554.  */
  555. void gaim_account_destroy_log(GaimAccount *account);
  556.  
  557. /*@}*/
  558.  
  559. /**************************************************************************/
  560. /** @name Accounts API                                                    */
  561. /**************************************************************************/
  562. /*@{*/
  563.  
  564. /**
  565.  * Loads the accounts.
  566.  *
  567.  * @return TRUE if accounts.xml was loaded successfully.  Otherwise
  568.  *         FALSE is returned.
  569.  */
  570. gboolean gaim_accounts_load();
  571.  
  572. /**
  573.  * Force an immediate write of accounts.
  574.  */
  575. void gaim_accounts_sync();
  576.  
  577. /**
  578.  * Adds an account to the list of accounts.
  579.  *
  580.  * @param account The account.
  581.  */
  582. void gaim_accounts_add(GaimAccount *account);
  583.  
  584. /**
  585.  * Removes an account from the list of accounts.
  586.  *
  587.  * @param account The account.
  588.  */
  589. void gaim_accounts_remove(GaimAccount *account);
  590.  
  591. /**
  592.  * Deletes an account.
  593.  *
  594.  * This will remove any buddies from the buddy list that belong to this
  595.  * account, buddy pounces that belong to this account, and will also 
  596.  * destroy @a account.
  597.  *
  598.  * @param account The account.
  599.  */
  600. void gaim_accounts_delete(GaimAccount *account);
  601.  
  602. /**
  603.  * Auto-logins to all accounts set to auto-login under the specified UI.
  604.  *
  605.  * @param ui The UI.
  606.  */
  607. void gaim_accounts_auto_login(const char *ui);
  608.  
  609. /**
  610.  * Reorders an account.
  611.  *
  612.  * @param account   The account to reorder.
  613.  * @param new_index The new index for the account.
  614.  */
  615. void gaim_accounts_reorder(GaimAccount *account, size_t new_index);
  616.  
  617. /**
  618.  * Returns a list of all accounts.
  619.  *
  620.  * @return A list of all accounts.
  621.  */
  622. GList *gaim_accounts_get_all(void);
  623.  
  624. /**
  625.  * Finds an account with the specified name and protocol id.
  626.  *
  627.  * @param name     The account username.
  628.  * @param protocol The account protocol ID.
  629.  *
  630.  * @return The account, if found, or @c FALSE otherwise.
  631.  */
  632. GaimAccount *gaim_accounts_find(const char *name, const char *protocol);
  633.  
  634. /*@}*/
  635.  
  636.  
  637. /**************************************************************************/
  638. /** @name UI Registration Functions                                       */
  639. /**************************************************************************/
  640. /*@{*/
  641. /**
  642.  * Sets the UI operations structure to be used for accounts.
  643.  *
  644.  * @param ops The UI operations structure.
  645.  */
  646. void gaim_accounts_set_ui_ops(GaimAccountUiOps *ops);
  647.  
  648. /**
  649.  * Returns the UI operations structure used for accounts.
  650.  *
  651.  * @return The UI operations structure in use.
  652.  */
  653. GaimAccountUiOps *gaim_accounts_get_ui_ops(void);
  654.  
  655. /*@}*/
  656.  
  657.  
  658. /**************************************************************************/
  659. /** @name Accounts Subsystem                                              */
  660. /**************************************************************************/
  661. /*@{*/
  662.  
  663. /**
  664.  * Returns the accounts subsystem handle.
  665.  *
  666.  * @return The accounts subsystem handle.
  667.  */
  668. void *gaim_accounts_get_handle(void);
  669.  
  670. /**
  671.  * Initializes the accounts subsystem.
  672.  */
  673. void gaim_accounts_init(void);
  674.  
  675. /**
  676.  * Uninitializes the accounts subsystem.
  677.  */
  678. void gaim_accounts_uninit(void);
  679.  
  680. /*@}*/
  681.  
  682. #ifdef __cplusplus
  683. }
  684. #endif
  685.  
  686. #endif /* _GAIM_ACCOUNT_H_ */
  687.